doc/build-waf.txt
author Tom Henderson <tomh@tomh.org>
Fri, 18 May 2007 10:27:42 -0700
changeset 657 be551a3b07c6
parent 635 71b92dfe5f55
child 672 184d5a505279
permissions -rw-r--r--
minor changes due to documentation review
tomh@657
     1
The main ns-3 build system is SCons.  Read the file build.txt
tomh@657
     2
for SCons instructions.
gjcarneiro@600
     3
tomh@657
     4
Waf is an alternative build system, similar to SCons.  ns-3 now is
tomh@657
     5
able to build with Waf, in parallel to SCons.
gjcarneiro@600
     6
tomh@657
     7
(http://www.freehackers.org/~tnagy/waf.html)
gjcarneiro@600
     8
tomh@657
     9
Note: the Waf build scripts are experimental at this stage.
tomh@657
    10
Gustavo Carneiro (gjcarneiro@gmail.com) is the maintainer.
gjcarneiro@600
    11
tomh@657
    12
=== Building with Waf ===
tomh@657
    13
tomh@657
    14
To build ns-3 with waf type the commands:
gjcarneiro@600
    15
 1. ./waf configure [options]
gjcarneiro@600
    16
 2. ./waf
gjcarneiro@600
    17
gjcarneiro@600
    18
[ Note: if ./waf does not exist, see the section "Note for developers" below ]
gjcarneiro@600
    19
gjcarneiro@600
    20
To see valid configure options, type ./waf --help.  The most important
gjcarneiro@600
    21
option is -d <debug level>.  Valid debug levels (which are listed in
gjcarneiro@600
    22
./waf --help) are: ultradebug, debug, release, and optimized.
gjcarneiro@600
    23
gjcarneiro@600
    24
The resulting binaries are placed in build/<debuglevel>/srcpath.
gjcarneiro@600
    25
gjcarneiro@600
    26
Other waf usages include:
gjcarneiro@600
    27
gjcarneiro@600
    28
 1. ./waf check
gjcarneiro@600
    29
    Runs the unit tests
gjcarneiro@600
    30
gjcarneiro@600
    31
 2. ./waf --doxygen
gjcarneiro@600
    32
    Run doxygen to generate documentation
gjcarneiro@600
    33
gjcarneiro@600
    34
 3. ./waf --lcov-report
gjcarneiro@600
    35
    Run code coverage analysis (assuming the project was configured
gjcarneiro@600
    36
with --enable-gcov)
gjcarneiro@600
    37
tomh@657
    38
=== Extending ns-3 ===
gjcarneiro@600
    39
gjcarneiro@600
    40
To add new modules:
gjcarneiro@600
    41
  1. Create the module directory under src (or src/devices, or whatever);
gjcarneiro@600
    42
  2. Add the source files to it;
gjcarneiro@600
    43
  3. Add a 'wscript' describing it;
gjcarneiro@600
    44
  4. Add the module subdirectory name to the all_modules list in src/wscript.
gjcarneiro@600
    45
tomh@657
    46
A module's wscript file is basically a regular Waf script.  A ns-3
gjcarneiro@600
    47
module is created as a cpp/shlib object, like this:
gjcarneiro@600
    48
gjcarneiro@600
    49
def build(bld):
gjcarneiro@600
    50
    obj = bld.create_obj('cpp', 'shlib')
gjcarneiro@600
    51
gjcarneiro@600
    52
    ## set module name; by convention it starts with ns3-
gjcarneiro@600
    53
    obj.name = 'ns3-mymodule'
gjcarneiro@600
    54
    obj.target = obj.name 
gjcarneiro@600
    55
gjcarneiro@600
    56
    ## list dependencies to other modules
gjcarneiro@600
    57
    obj.uselib_local = ['ns3-core'] 
gjcarneiro@600
    58
gjcarneiro@600
    59
    ## list source files (private or public header files excluded)
gjcarneiro@600
    60
    obj.source = [
gjcarneiro@600
    61
        'mymodule.cc',
gjcarneiro@600
    62
    ]
gjcarneiro@600
    63
gjcarneiro@600
    64
    ## list module public header files
gjcarneiro@600
    65
    headers = bld.create_obj('ns3header')
gjcarneiro@600
    66
    headers.source = [
gjcarneiro@600
    67
        'mymodule-header.h',
gjcarneiro@600
    68
    ]
gjcarneiro@600
    69
gjcarneiro@600
    70
gjcarneiro@600
    71
=== Note for developers ===
gjcarneiro@600
    72
tomh@657
    73
The ns-3 code repository does not contain the waf script.  Instead,
gjcarneiro@600
    74
developers should check it out from a subversion repository:
gjcarneiro@600
    75
gjcarneiro@602
    76
  svn checkout http://waf.googlecode.com/svn/tags/ns3/ waf
gjcarneiro@602
    77
gjcarneiro@602
    78
[ note: 'tags/ns3' is a tag that represents the last svn version
gjcarneiro@602
    79
tested to work correctly with ns3, although 'trunk' will likely work
gjcarneiro@602
    80
 as well ]
gjcarneiro@600
    81
gjcarneiro@600
    82
Then it can be installed system-wide with 'sudo ./waf-light install'.
gjcarneiro@600
    83
When preparing a distribution, the resulting 'waf' script, which is
gjcarneiro@600
    84
self contained (no external files needed), can be easily included in
tomh@657
    85
the tarball so that users downloading ns-3 can easily build it without
tomh@657
    86
having Waf installed (although Python >= 2.3 is still needed).
gjcarneiro@600
    87
gjcarneiro@600
    88
The command 'waf dist' can be used to create a distribution tarball.
gjcarneiro@600
    89
It includes all files in the source directory, except some particular
gjcarneiro@600
    90
extensions that are blacklisted, such as back files (ending in ~).
gjcarneiro@600
    91