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 ===

If this file is part of a development release tarball, the top-level 

ns-3 directory should contain a current waf script.

However, the ns-3 Mercurial code repository does not contain the waf 

script.  Instead, developers should check it out from a subversion 

repository:

  svn checkout http://waf.googlecode.com/svn/tags/ns3/ waf

[ note: 'tags/ns3' is a tag that represents the last svn version

tested to work correctly with ns3, although 'trunk' will likely work

 as well ]

Then it can be installed system-wide with 'sudo waf-light install'.

When preparing a distribution, the resulting 'waf' script, which is

self contained (no external files needed), can be easily included in

the tarball so that users downloading ns-3 can easily build it without

having Waf installed (although Python >= 2.3 is still needed).

=== Building with Waf ===

To build ns-3 with waf type the commands:

 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: ultradebug, debug, release, and optimized.  It is

also possible to change the flags used for compilation with (e.g.):

CXXFLAGS="-O3" 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.

Other waf usages include:

 1. waf check

    Runs the unit tests

 2. waf --doxygen

    Run doxygen to generate documentation

 3. waf --lcov-report

    Run code coverage analysis (assuming the project was configured

with --enable-gcov)

 4. waf --run "program [args]"

    Run a ns3 program, given its target name, with the given

    arguments.  This takes care of automatically modifying the the

    path for finding the ns3 dynamic libraries in the environment

    before running the program.  Note: the "program [args]" string is

    parsed using POSIX shell rules.

 5. waf --shell

    Starts a nested system shell with modified environment to run ns3 programs.

 6. waf distclean

    Cleans out the entire build/ directory

 7. waf dist

    The command 'waf dist' can be used to create a distribution tarball.

    It includes all files in the source directory, except some particular

    extensions that are blacklisted, such as back files (ending in ~).

=== Extending ns-3 ===

To add new modules:

  1. Create the module directory under src (or src/devices, or whatever);

  2. Add the source files to it;

  3. Add a 'wscript' describing it;

  4. Add the module subdirectory name to the all_modules list in src/wscript.

A module's wscript file is basically a regular Waf script.  A ns-3

module is created as a cpp/shlib object, like this:

def build(bld):

    obj = bld.create_obj('cpp', 'shlib')

    ## set module name; by convention it starts with ns3-

    obj.name = 'ns3-mymodule'

    obj.target = obj.name 

    ## list dependencies to other modules

    obj.uselib_local = ['ns3-core'] 

    ## list source files (private or public header files excluded)

    obj.source = [

        'mymodule.cc',

    ]

    ## list module public header files

    headers = bld.create_obj('ns3header')

    headers.source = [

        'mymodule-header.h',

    ]