3 Getting Started
3.1 Review
3.2 Prerequisites
3.2.1 Downloading the ns-3 release as a source archive
3.3 Downloading ns-3 with Git
3.3.1 Loading ns-3 with Bake
3.4 Assembly ns-3
3.4.1 Building with build.py
3.4.2 Building with Bake
3.4.3 Building with Waf
3.5 Testing ns-3
3.6 Run script
3.6.1 Command line arguments
3.6.2 Debugging
3.6.3 Working directory
Chapter 3
Getting Started
This chapter aims to get the reader ready to start on a computer that may never have had ns-3 installed. It covers supported platforms, prerequisites, how to get ns-3, how to build ns-3, and how to test your build and run simple programs.
3.1 Review
The ns-3 simulator is built as a system of collaborative software libraries. When built, user program code is linked against these libraries. To write custom programs, C++ or Python programming languages ββare used.
Ns-3 is distributed as source code, which means that the target system must have a software development environment in order to first build the libraries and then build the user program. In principle, ns-3 can be distributed as ready-made libraries for a specific system, and in the future they can be distributed in this way. But these days, many users actually do their work by editing ns-3 itself, so it's useful to have the source code to build the libraries. If someone would like to take on the job of creating ready-made libraries and packages for operating systems, please contact the mailing list ns-developers.
Next, we will look at three ways to download and build ns-3. The first is to download and build the official release from the main site. The second is the selection and assembly of copies of development versions of the base ns-3 installation. The third is using additional build tools to load more extensions for ns-3. We'll go through each one, as the tools are slightly different.
Experienced Linux users may wonder why ns-3 is not provided as a package like most other libraries using a package manager? Although there are binary packages for various Linux distributions (eg Debian), most users end up editing the libraries and having to rebuild ns-3 themselves, so having the source available is convenient. For this reason, we will focus on installing from source.
For most applications ns-3 rights root are not needed, it is recommended to use an unprivileged user account.
3.2 Prerequisites
The entire set of available ns-3 libraries has a number of dependencies on third-party libraries, but for the most part ns-3 can be built and used with support for several common (often installed by default) components: C++ compiler, Python, source code editor (for example, vim, emacs or Eclipse) and, if development repositories are used, Git version control systems. Most novice users need not worry if their configuration reports some missing extra ns-3 features, but for those who desire a full install, the project provides a wiki that includes pages with many helpful tips and tricks. One such page is the "Installation" page with installation instructions for various systems, available at: .
The "Prerequisites" section of this wiki page explains which packages are required to support common ns-3 options and also provides the commands used to install them on common Linux or macOS flavors.
You can take the opportunity to explore the ns-3 wiki or the main website: because there is a lot of information there. Starting with the latest version of ns-3 (ns-3.29), the following tools are required to run ns-3:
Tool Package/Version
- C++ compiler
clang++ or g++ (g++ version 4.9 or greater) - Python
python2 version >= 2.7.10, or python3 version >=3.4 - Go
any latest version (to access ns-3 on GitLab.com) - tar
any latest version (for unpacking ns-3 release) - bunzip2
any recent version (for unpacking ns-3 release)
To check the default Python version, type python -V. To check the version of g++, type g++ -v. If any tools are missing or too old, refer to the installation guide on the ns-3 wiki page.
From now on, we assume that the reader is running Linux, MacOS, or a Linux environment emulator, and has at least the above tools.
3.2.1 Downloading the ns-3 release as a source archive
This is the way to go for a new user who wants to download and play with the latest release and package versions of ns-3. ns-3 releases are published as compressed source archives, sometimes referred to as tarball. tarball is a special software archive format in which several files are combined together. The archive is usually compressed. ns-3 boot process via tarball is simple, you just need to select a release, download and unpack it.
Let's assume that you, as a user, want to build ns-3 in a local directory named work space. You can get a working copy of the release by typing the following into the Linux console (substituting the appropriate version numbers, of course)
$ cd
$ mkdir workspace
$ cd workspace
$ wget https://www.nsnam.org/release/ns-allinone-3.29.tar.bz2
$ tar xjf ns-allinone-3.29.tar.bz2 Pay attention to the utility used above wget, which is a command line tool for downloading objects from the Internet. If you haven't installed it, you can use your browser to do it.
Following these steps will change to the ns-allinone-3.29 directory where you should see several files and directories
$ cd ns-allinone-3.29
$ ls
bake constants.py ns-3.29 README
build.py netanim-3.108 pybindgen-0.17.0.post58+ngcf00cc0 util.pyYou are now ready to build the base ns-3 distribution and can move on to the section on building ns-3.
3.3 Downloading ns-3 with Git
The ns-3 code is available in the Git repositories on GitLab.com at . Group nsnam brings together various repositories used by an open source project.
The easiest way to start using Git repositories is to fork or clone the environment. ns-3-allinone. This is a set of scripts that manages the loading and building of the most commonly used ns-3 subsystems. If you're new to Git, the terms "fork" and "clone" may be unfamiliar to you; if so, we recommend that you simply clone (make your own copy of) the GitLab.com repository as follows:
$ cd
$ mkdir workspace
$ cd workspace
$ git clone https://gitlab.com/nsnam/ns-3-allinone.git
$ cd ns-3-allinone At this point, your directory view ns-3-allinone slightly different from the release archive directory described above. It should look something like this:
$ ls
build.py constants.py download.py README util.pyPay attention to the presence of the script download.py, which will additionally extract ns-3 and accompanying source code. Here you have a choice: either download the latest ns-3 development snapshot:
$ python download.pyor prefer the ns-3 release using the flag -n to specify the release number:
$ python download.py -n ns-3.29After this step in the directory ns-3-allinone additional repositories will be downloaded ns-3, bake, pybindgen ΠΈ netanim.
Note
On a clean Ubuntu16.04 machine, I needed to change the command to look like this: $ sudo python3 download.py -n ns-3.29 (hereinafter the translator's notes).
3.3.1 Loading ns-3 with Bake
The above two methods (source archive or repository ns-3-allinone via Git) are useful for getting the simplest ns-3 installation with a few addons(pybindgen to generate Python bindings, and netanim to animate the network). The third repository provided by default in ns-3-allinone is called bake.
Beacon is a multi-repository coordinated build tool developed for the ns-3 project. Beacon can be used to obtain development versions of ns-3, as well as to download and build extensions to the base version of the ns-3 distribution, such as the environment Direct Code Execution, Cradle Network Simulation Cradle, the ability to create new Python bindings, and various ns-3 "applications".
Note
CradleNetwork Simulation Cradle is a framework that allows you to use real TCP / IP network stacks inside a network simulator.
If you think your ns-3 installation should have advanced or additional features, you can follow this installation path.
In recent releases of ns-3 Beacon has been added to the tar release. The release includes a configuration file that allows you to download the latest versions of the software at the time the release was created. That is, for example, version Beacon, which is distributed with the ns-3.29 release, can be used to retrieve components for that ns-3 release or earlier, but cannot be used to retrieve components for later releases (if the package descriptor file bakeconf.xml not updated).
You can also get the latest copy bakeby entering the following command into your Linux console (assuming you have Git installed):
$ cd
$ mkdir workspace
$ cd workspace
$ git clone https://gitlab.com/nsnam/bake.gitWhile running the git command, you should see something like the following:
Cloning into 'bake'...
remote: Enumerating objects: 2086, done.
remote: Counting objects: 100% (2086/2086), done.
remote: Compressing objects: 100% (649/649), done.
remote: Total 2086 (delta 1404), reused 2078 (delta 1399)
Receiving objects: 100% (2086/2086), 2.68 MiB | 3.82 MiB/s, done.
Resolving deltas: 100% (1404/1404), done.After the command completes clones you should have a directory named bake, whose contents should look something like this:
$ cd bake
$ ls
bake bakeconf.xml bake.py doc examples generate-binary.py test TODONote that you have loaded several Python scripts, a Python module named bake and an XML configuration file. The next step is to use these scripts to download and build the ns-3 distribution of your choice. Several customization targets are available:
-
ns-3.29: module corresponding to the release; it will download components similar to the release tarball;
-
ns-3-dev: similar module, but using code from the development tree;
-
ns-allinone-3.29: A module that includes other advanced features such as Click Routing and Network Simulation Cradle, Openflow for ns-3.
-
ns-3-allinone: similar to the release version of the module allinone, but for development code.
Note
Click - modular software architecture for creating routers.
Openflow is a protocol for managing the processing of data transmitted over a data network by routers and switches, which implements the technology of a software-defined network.
The current development snapshot (non-release) of ns-3 can be found at:.
The developers try to keep these repositories in a consistent working state, but they are in the development area and there is non-release code in them, so if you do not plan to use new features, then choose the official release.
You can find the latest version of the code by browsing the list of repositories, or by going to the ns-3 Releases webpage: and clicking on the link for the latest version. In this example, we will continue with ns-3.29.
Now, to get the ns-3 components we need, we use the tool Beacon. Let's say a few introductory words about the work Beacon.
Bake works by downloading package sources into a directory source and installing libraries in the build directory. Beacon can be run by referencing the binary, but if you want to run Beacon not from the directory in which it was downloaded, it is advisable to add the path to bake to your path (PATH environment variable), for example, as follows (example for the Linux bash shell). Change to the "bake" directory and then set the following environment variables:
$ export BAKE_HOME=`pwd`
$ export PATH=$PATH:$BAKE_HOME:$BAKE_HOME/build/bin
$ export PYTHONPATH=$PYTHONPATH:$BAKE_HOME:$BAKE_HOME/build/libThis will place the program bake.py to the shell path and allow other programs to find the executables and libraries it created bake. In some use cases bake, the PATH and PYTHONPATH setting described above is not required, but a full build of ns-3-allinone (with additional packages) usually does.
Go to the working directory and enter the following in the console:
$ ./bake.py configure -e ns-3.29Next, we will ask Beacon check if we have enough tools to download various components. Dial:
$ ./bake.py checkYou should see something like the following:
> Python - OK
> GNU C++ compiler - OK
> Mercurial - OK
> Git - OK
> Tar tool - OK
> Unzip tool - OK
> Make - OK
> cMake - OK
> patch tool - OK
> Path searched for tools: /usr/local/sbin /usr/local/bin /usr/sbin /usr/bin /sbin /bin ...In particular, download tools such as Mercurial, CVS, Git, and Bazaar are essential in this step, as they allow us to get the code. At this point, install the missing tools in the usual way for your system (if you know how) or contact your system administrator for help.
Next, try downloading the software:
$ ./bake.py downloadthe result should be something like:
>> Searching for system dependency setuptools - OK
>> Searching for system dependency libgoocanvas2 - OK
>> Searching for system dependency gi-cairo - OK
>> Searching for system dependency pygobject - OK
>> Searching for system dependency pygraphviz - OK
>> Searching for system dependency python-dev - OK
>> Searching for system dependency qt - OK
>> Searching for system dependency g++ - OK
>> Downloading pybindgen-0.19.0.post4+ng823d8b2 (target directory:pybindgen) - OK
>> Downloading netanim-3.108 - OK
>> Downloading ns-3.29 - OKThis will mean that three sources have been downloaded. Now change to the source directory and type ls; You should see:
$ cd source
$ ls
netanim-3.108 ns-3.29 pybindgenYou are now ready to build the ns-3 distribution.
3.4 Assembly ns-3
As with downloading ns-3, there are several ways to build ns-3. The main thing we want to emphasize is that ns-3 is built with a build tool called wafdescribed below. Most users will work with waf, but there are some handy scripts to help you start or organize more complex builds. So please before you read about waf, take a look at build.py and assembly with bake.
3.4.1 Building with build.py
Attention! This build step is only available from the version of the source archive obtained as described above; not downloaded via git or bake.
When working with a release archive tarballIn ns-3-allinone There is a handy script that can make it easier to assemble components. It's called build.py. This program will set up the project for you in the most useful way. However, note that more advanced setup and work with ns-3 usually involves using ns-3's own build system, Waf, which will be introduced later in this guide.
If you downloaded with tarball, then in your directory ~/workspace there should be a directory named something like ns-allinone-3.29. Enter the following:
$ ./build.py --enable-examples --enable-tests
On call build.py we have used command-line arguments to build the examples and tests used in this tutorial that are not built by default in ns-3. By default, the program also builds all available modules. Then, if you wish, you can build ns-3 without examples and tests, or exclude modules that are not needed for your work.
You will see many compiler output messages displayed by the script as it builds the various parts you downloaded. First the script will try to build the animator netanim, then the binding generator pybindgen and finally ns-3. At the end of the process, you should see the following:
Waf: Leaving directory '/path/to/workspace/ns-allinone-3.29/ns-3.29/build'
'build' finished successfully (6m25.032s)
Modules built:
antenna aodv applications
bridge buildings config-store
core csma csma-layout
dsdv dsr energy
fd-net-device flow-monitor internet
internet-apps lr-wpan lte
mesh mobility mpi
netanim (no Python) network nix-vector-routing
olsr point-to-point point-to-point-layout
propagation sixlowpan spectrum
stats tap-bridge test (no Python)
topology-read traffic-control uan
virtual-net-device visualizer wave
wifi wimax
Modules not built (see ns-3 tutorial for explanation):
brite click openflow
Leaving directory ./ns-3.29In the last three lines of the listing, we see a message about modules that were not built:
Modules not built (see ns-3 tutorial for explanation):
brite clickIt simply means that some ns-3 modules that depend on external libraries may not have been built, or that they do not need to be built for this configuration. This does not mean that the simulator has not been built or that the assembled modules will not work correctly.
3.4.2 Building with Bake
If you used bake above to get the source code from the project repositories, you can continue to use it to build ns-3 as well. Dial:
$ ./bake.py buildand you should see something like:
>> Building pybindgen-0.19.0.post4+ng823d8b2 - OK
>> Building netanim-3.108 - OK
>> Building ns-3.29 - OKHelp: You can also do both download and build steps at once by calling "bake.py deploy".
When building all components, failures are possible, but the assembly will continue if the component is not required. For example, a recent portability issue was that castxml can be assembled by tool bake not on all platforms. In this case, a message like this will appear:
>> Building castxml - Problem
> Problem: Optional dependency, module "castxml" failed
This may reduce the functionality of the final build.
However, bake will continue since "castxml" is not an essential dependency.
For more information call bake with -v or -vvv, for full verbose mode.But castxml only needed if you want to create updated Python bindings. For most users, there is no need for this (at least until they change ns-3), so these warnings can be safely ignored for now.
If it fails, then the following command will give you a hint about missing dependencies:
$ ./bake.py showThe various dependencies of the packages you are trying to build will be listed.
3.4.3 Building with Waf
Up to this point, to start building ns-3, we have used either the script build.py, or a tool bake. These tools are useful for building ns-3 and maintaining libraries. In fact, to build they run the build tool waf from the ns-3 directory. waf installed with the ns-3 source code. Most users to configure and build ns-3 quickly move to direct use waf. So, to continue, please change to the ns-3 directory that you originally created.
It's not strictly required at this point, but it's useful to take a step back and see how to make changes to the project's configuration. Probably the most useful configuration change you can make is to create an optimized version of the code. By default, you have configured your project to build the debug version. Let's take a look at the project to create an optimized build. To explain to Waf that it should make optimized builds that include examples and tests, you will need to run the following commands:
$ ./waf clean
$ ./waf configure --build-profile=optimized --enable-examples --enable-testsThis will launch waf outside the local directory (for your convenience). The first command cleans up the previous build, it's usually not strictly necessary, but it's good practice (also see build profiles below); this will remove the previously created libraries and object files found in the directory build /. When the project is reconfigured and the build system checks for various dependencies, you should see output similar to the following:
Setting top to : /home/ns3user/workspace/bake/source/ns-3-dev
Setting out to : /home/ns3user/workspace/bake/source/ns-3-dev/build
Checking for 'gcc' (C compiler) : /usr/bin/gcc
Checking for cc version : 7.3.0
Checking for 'g++' (C++ compiler) : /usr/bin/g++
Checking for compilation flag -march=native support : ok
Checking for compilation flag -Wl,--soname=foo support : ok
Checking for compilation flag -std=c++11 support : ok
Checking boost includes : headers not found, please ,!provide a --boost-includes argument (see help)
Checking boost includes : headers not found, please ,!provide a --boost-includes argument (see help)
Checking for program 'python' : /usr/bin/python
Checking for python version >= 2.3 : 2.7.15 python-config : /usr/bin/python-config
Asking python-config for pyembed '--cflags --libs --ldflags' flags : yes
Testing pyembed configuration : yes
Asking python-config for pyext '--cflags --libs --ldflags' flags : yes
Testing pyext configuration : yes
Checking for compilation flag -fvisibility=hidden support : ok
Checking for compilation flag -Wno-array-bounds support : ok
Checking for pybindgen location : ../pybindgen ,!(guessed)
Checking for python module 'pybindgen' : 0.19.0. ,!post4+g823d8b2
Checking for pybindgen version : 0.19.0. ,!post4+g823d8b2
Checking for code snippet : yes
Checking for types uint64_t and unsigned long equivalence : no
Checking for code snippet : no
Checking for types uint64_t and unsigned long long equivalence : yes
Checking for the apidefs that can be used for Python bindings : gcc-LP64
Checking for internal GCC cxxabi : complete
Checking for python module 'pygccxml' : not found
Checking for click location : not found
Checking for program 'pkg-config' : /usr/bin/pkg- ,!config
Checking for 'gtk+-3.0' : not found
Checking for 'libxml-2.0' : yes
checking for uint128_t : not found
checking for __uint128_t : yes
Checking high precision implementation : 128-bit integer ,!(default)
Checking for header stdint.h : yes
Checking for header inttypes.h : yes
Checking for header sys/inttypes.h : not found
Checking for header sys/types.h : yes
Checking for header sys/stat.h : yes
Checking for header dirent.h : yes
Checking for header stdlib.h : yes
Checking for header signal.h : yes
Checking for header pthread.h : yes
Checking for header stdint.h : yes
Checking for header inttypes.h : yes
Checking for header sys/inttypes.h : not found
Checking for library rt : yes
Checking for header sys/ioctl.h : yes
Checking for header net/if.h : yes
Checking for header net/ethernet.h : yes
Checking for header linux/if_tun.h : yes
Checking for header netpacket/packet.h : yes
Checking for NSC location : not found
Checking for 'sqlite3' : not found
Checking for header linux/if_tun.h : yes
Checking for python module 'gi' : 3.26.1
Checking for python module 'gi.repository.GObject' : ok
Checking for python module 'cairo' : ok
Checking for python module 'pygraphviz' : 1.4rc1
Checking for python module 'gi.repository.Gtk' : ok
Checking for python module 'gi.repository.Gdk' : ok
Checking for python module 'gi.repository.Pango' : ok
Checking for python module 'gi.repository.GooCanvas' : ok
Checking for program 'sudo' : /usr/bin/sudo
Checking for program 'valgrind' : not found
Checking for 'gsl' : not found python-config : not found
Checking for compilation flag -fstrict-aliasing support : ok
Checking for compilation flag -fstrict-aliasing support : ok
Checking for compilation flag -Wstrict-aliasing support : ok
Checking for compilation flag -Wstrict-aliasing support : ok
Checking for program 'doxygen' : /usr/bin/doxygen
---- Summary of optional ns-3 features:
Build profile : optimized
Build directory :
BRITE Integration : not enabled (BRITE not enabled (see option --with- ,!brite))
DES Metrics event collection : not enabled (defaults to disabled)
Emulation FdNetDevice : enabled
Examples : enabled
File descriptor NetDevice : enabled
GNU Scientific Library (GSL) : not enabled (GSL not found)
Gcrypt library : not enabled
(libgcrypt not found: you can use ,!libgcrypt-config to find its location.) GtkConfigStore : not enabled (library 'gtk+-3.0 >= 3.0' not fou nd)
MPI Support : not enabled (option --enable-mpi not selected)
ns-3 Click Integration : not enabled (nsclick not enabled (see option --with- ,!nsclick))
ns-3 OpenFlow Integration : not enabled (Required boost libraries not found)
Network Simulation Cradle : not enabled (NSC not found (see option --with-nsc))
PlanetLab FdNetDevice : not enabled (PlanetLab operating system not detected ,!(see option --force-planetlab)) PyViz visualizer : enabled
Python API Scanning Support : not enabled (Missing 'pygccxml' Python module)
Python Bindings : enabled
Real Time Simulator : enabled
SQlite stats data output : not enabled (library 'sqlite3' not found)
Tap Bridge : enabled
Tap FdNetDevice : enabled
Tests : enabled
Threading Primitives : enabled
Use sudo to set suid bit : not enabled (option --enable-sudo not selected)
XmlIo : enabled
'configure' finished successfully (6.387s)Pay attention to the last part of the above listing. Some ns-3 options are not enabled by default or require support from the system to work properly. For example, to enable XmlTo, the system must have the library libxml-2.0. If this library was not found and the corresponding ns-3 feature would not be enabled, a message will be displayed. Also note that it is possible to use the command sudo to set the suid bit "set group ID at runtime" for certain programs. It is not enabled by default and therefore this feature is displayed as "not enabled". Finally, to get a list of enabled options, use waf with parameter --check-config.
Now let's go back and switch back to the debug build containing the examples and tests.
$ ./waf clean
$ ./waf configure --build-profile=debug --enable-examples --enable-testsThe build system is now set up and you can build debug versions of ns-3 programs by simply typing:
$ ./wafWhile the steps above may have forced you to build part of the ns-3 system twice, now you know how to reconfigure and build optimized code.
To check which profile is active for a given project configuration, there is a command:
$ ./waf --check-profile
Waf: Entering directory `/path/to/ns-3-allinone/ns-3.29/build'
Build profile: debugThe above scenario build.py also supports arguments --enable-examples ΠΈ --enable-tests, but other options waf it does not support directly. For example, this will not work:
$ ./build.py --disable-pythonthe reaction will be like this:
build.py: error: no such option: --disable-pythonHowever, the special operator - - can be used to pass additional parameters via WAF, so the following command will work instead of the above:
$ ./build.py -- --disable-pythonbecause it generates the main command ./waf configure --disable-python. Here are some more introductory tips about waf.
Build Error Handling
ns-3 releases are tested on the latest C++ compilers available at the time of release on common Linux and MacOS distributions. However, over time, new distributions are released with new compilers, and these newer compilers tend to be more pedantic about warnings. ns-3 configures its build to treat all warnings as errors, so sometimes if you're running an older version on a newer system, a compiler warning can stop the build.
For example, there was previously a release of ns-3.28 for Fedora 28 which included a new major version gcc (gcc-8). Building release ns-3.28 or earlier under Fedora 28 with Gtk2+ installed will generate the following error:
/usr/include/gtk-2.0/gtk/gtkfilechooserbutton.h:59:8: error: unnecessary parentheses ,!in declaration of β__gtk_reserved1β [-Werror=parentheses] void (*__gtk_reserved1);In releases starting with ns-3.28.1, waf an option is available to solve these problems. It disables setting the "-Werror" flag in g++ and clang++. This is the "--disable-werror" option, it must be applied during configuration:
$ ./waf configure --disable-werror --enable-examples --enable-testsconfigure or collect
Some commands waf are only meaningful in the configure phase, and some are valid only in the build phase. For example, if you want to use the ns-3 emulation features, you can turn on the bit setting suid using sudoas described above. This will override the configuration step commands, so you can change the configuration using the following command, which also includes examples and tests.
$ ./waf configure --enable-sudo --enable-examples --enable-testsIf you do it waf launch sudoto change emulation code socket programs to run with rights root. In waf many more options are available for the configuration and build steps. To explore options, type:
$ ./waf --helpIn the next section, we will use some options related to testing.
Build profiles
We have already seen how to set up waf for assemblies debugging ΠΈ optimized:
$ ./waf --build-profile=debugThere is also an intermediate build profile, release. Option -d is synonymous with --build-profile. The build profile controls the use of logging, assertions, and compiler optimization switches:
As you can see, logging and assertions are only available in debug builds. The recommended practice is to develop your script in debug mode, then run iteratively (for statistics or parameter changes) in an optimized build profile.
If you have code that should only run in certain build profiles, use the Code Wrapper Macro:
NS_BUILD_DEBUG (std::cout << "Part of an output line..." << std::flush; timer.Start ,!()); DoLongInvolvedComputation ();
NS_BUILD_DEBUG (timer.Stop (); std::cout << "Done: " << timer << std::endl;)Default, waf places the build artifacts in the build directory. You can specify a different output directory with the option -β―-out, For example:
$ ./waf configure --out=my-build-dirBy combining this with build profiles, you can easily switch between different compilation options:
$ ./waf configure --build-profile=debug --out=build/debug
$ ./waf build
...
$ ./waf configure --build-profile=optimized --out=build/optimized
$ ./waf build
...This allows you to work with multiple builds without having to rewrite the latest build each time. When you switch to another profile, waf will only compile it, without completely recompiling everything.
When you switch build profiles in this way, care must be taken to give the same configuration options each time. You can avoid errors by defining a few environment variables:
$ export NS3CONFIG="--enable-examples --enable-tests"
$ export NS3DEBUG="--build-profile=debug --out=build/debug"
$ export NS3OPT=="--build-profile=optimized --out=build/optimized"
$ ./waf configure $NS3CONFIG $NS3DEBUG
$ ./waf build
...
$ ./waf configure $NS3CONFIG $NS3OPT
$ ./waf buildCompilers and flags
In the examples above waf to build ns-3 uses the C++ compiler from GCC ( g ++). However, you can change the used waf C++ compiler, by defining the CXX environment variable. For example, to use the C++ compiler Clang, clang++,
$ CXX="clang++" ./waf configure
$ ./waf build Similarly, you can set waf to use distributed compilation with distcc:
$ CXX="distcc g++" ./waf configure
$ ./waf buildMore information about distcc and distributed compilation can be found on the project page in the Documentation section. To add compiler flags when configuring ns-3, use the CXXFLAGS_EXTRA environment variable.
Installation
waf can be used to install libraries in different places on the system. By default, the built libraries and executables are located in the directory build, and since Waf knows the location of these libraries and executables, there is no need to install the libraries anywhere else.
If users prefer to install outside the build directory, they can run the command ./waf install. The default prefix for installation is / usr / localSo ./waf install will install programs in / usr / local / bin, libraries in / Usr / local / lib and header files in /usr/local/include. Superuser permissions usually need to be set with the default prefix, so a typical command would be sudo ./waf install. On startup, Waf will first choose to use the shared libraries in the build directory, then it will look for libraries in the path of the libraries configured in the local environment. So when installing libraries on a system, it's good practice to check that the correct libraries are being used. Users can choose to install with a different prefix by passing the option during configuration --prefix, For example:
./waf configure --prefix=/opt/localIf later, after the build, the user enters the install command ./waf, prefix will be used /opt/local.
Team ./waf clean must be used before project migration if the installation will use waf under a different prefix.
Thus, to use ns-3, there is no need to call ./waf install. Most users will not need this command because waf will pick up the current libraries from the build directory, but some users may find this useful if their activity involves working with programs outside the ns-3 directory.
waf single
At the top level of the ns-3 source tree, there is only one Waf script. Once you start working, you will spend a lot of time in the directory scratch/ or deeper intosrc/... and at the same time have the need to run waf. You can just remember where you are and run waf in the following way:
$ ../../../waf ...but that will be tedious and error prone so there are better solutions. One common way is to use a text editor such as emacs or vim, which opens two terminal sessions, one used to build ns-3 and the other to edit the source code. If you only have tarball, then an environment variable can help:
$ export NS3DIR="$PWD"
$ function waff { cd $NS3DIR && ./waf $* ; }
$ cd scratch
$ waff buildIn the module directory it might be tempting to add a trivial waf script like exec ../../waf. Please, do not do that. This is confusing for beginners and, if done poorly, leads to hard-to-find build errors. The solutions shown above are the way to go.
3.5 Testing ns-3
You can unit test the ns-3 distribution by running the script ./test.py:
$ ./test.pyThese tests are run in parallel with waf. Eventually you should see a message saying that
92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors)This is an important message for identifying valgrind crashes, crashes or errors, code problems or incompatibilities between tools and code.
You will also see the final output from waf and a tester running each test, which would look something like this:
Waf: Entering directory `/path/to/workspace/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/path/to/workspace/ns-3-allinone/ns-3-dev/build'
'build' finished successfully (1.799s)
Modules built:
aodv applications bridge
click config-store core
csma csma-layout dsdv
emu energy flow-monitor
internet lte mesh
mobility mpi netanim
network nix-vector-routing ns3tcp
ns3wifi olsr openflow
point-to-point point-to-point-layout propagation
spectrum stats tap-bridge
template test tools
topology-read uan virtual-net-device
visualizer wifi wimax
PASS: TestSuite ns3-wifi-interference
PASS: TestSuite histogram
...
PASS: TestSuite object
PASS: TestSuite random-number-generators
92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors)
This command is typically run by users to quickly verify that the ns-3 distribution has been built correctly. (Note that the order of the "PASS: ..." lines may vary, this is normal. The important thing is that in the summary line at the end of the report, all tests pass; no test fails or crashes.) And wafand test.py will parallelize work across the machine's available processor cores.
3.6 Run script
We usually run scripts under control waf. This allows the build system to ensure that the shared library paths are set correctly and that the libraries are available at runtime. To run the program, just use waf with parameter -β―-run. Run the ns-3 equivalent of the ubiquitous program hello worldby typing the following:
$ ./waf --run hello-simulatorWaf will first check that the program is built correctly and build if necessary. Then waf will execute a program that will produce the following output.
Hello SimulatorCongratulations! You are now an ns-3 user!
What should I do if I don't see results?
If you see messages waf, indicating that the build completed successfully, but you don't see the output Hello Simulator, then it is likely that you in the [Build-with-Waf] section switched your build mode to optimized, but missed switching back to the mode debugging. All console output used in this tutorial uses a special ns-3 logging component and is used to print custom messages to the console. The output from this component is automatically disabled when the optimized code is compiled - it is "optimized". If you don't see the "Hello Simulator" output, type the following:
$ ./waf configure --build-profile=debug --enable-examples --enable-teststo customize waf to build debug versions of ns-3 programs that include examples and tests. You must then rebuild the current debug version of the code by typing
$ ./wafNow if you run the program hello simulator, you should see the expected result.
3.6.1 Command line arguments
To pass command line arguments to an ns-3 program, use the following pattern:
$ ./waf --run <ns3-program> --command-template="%s <args>"Replace to the name of your program and to the arguments. Argument -β―-command-template for waf is essentially a recipe for building the actual command line waf used to execute the program. Waf checks that the build is complete, sets the shared library paths, then using the provided command line template and substituting the program name for the %s placeholder, calls the executable. If this syntax seems complicated to you, there is a simpler version that includes the ns-3 program and its arguments enclosed in single quotes:
$ ./waf --run '<ns3-program> --arg1=value1 --arg2=value2 ...'Another particularly useful example is the selective running of test suites. Let's assume that there is a test suite (suite) mytest (in fact, it does not exist). Above, we used the ./test.py script to run a number of tests in parallel, which repeatedly calls the test program test-runner. Call test-runner directly to run a single test:
$ ./waf --run test-runner --command-template="%s --suite=mytest --verbose"Arguments will be passed to the program test-runner. Since mytest does not exist, an error message will be generated. To print the available options for test-runner, type:
$ ./waf --run test-runner --command-template="%s --help"3.6.2 Debugging
To run ns-3 programs under another utility, such as a debugger (for example, gdb) or a memory test tool (for example, valgrind), use a similar form -β―-command-template = "β¦". For example, to run in the debugger gdb your hello-simulator ns-3 program with arguments :
$ ./waf --run=hello-simulator --command-template="gdb %s --args <args>"Note that the program name ns-3 comes with an argument -β―-run, and the control utility (here gdb) is the first token in the argument -β―-command-template. Option -β―-args ΡΠΎΠΎΠ±ΡΠ°Π΅Ρ gdbthat the rest of the command line belongs to the "inferior" program. (Some versions gdb don't understand the option -β―-args. In this case, remove the program arguments from -β―-command-template and use the command set gdb args.) We can combine this recipe and the previous one to run the test under a debugger:
$ ./waf --run test-runner --command-template="gdb %s --args --suite=mytest --verbose"3.6.3 Working directory
Waf must be launched from its location at the top of the ns-3 tree. This folder becomes the working directory where the output files will be written. But what if you want to keep these files outside the ns-3 source tree? Use an argument -β―-cwd:
$ ./waf --cwd=...You may find it more convenient to get the output files in your working directory. In this case, this indirect action can help:
$ function waff {
CWD="$PWD"
cd $NS3DIR >/dev/null
./waf --cwd="$CWD" $*
cd - >/dev/null
}This decoration of the previous version of the command saves the current working directory, changes to the directory wafand then instructs waf to change the working directory back to the current working directory saved before starting the program. We mention the team -β―-cwd for the sake of completeness, most users simply run Waf from the top level directory and generate output files there.
Source: habr.com