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