Remove doc/build-waf.txt ns-3.0.4
authorTom Henderson <tomh@tomh.org>
Mon, 16 Jul 2007 22:43:10 -0700
changeset 9305701e60bf01a
parent 929 9394956b7fc4
child 931 25ed9ed4a675
Remove doc/build-waf.txt
doc/build-waf.txt
     1.1 --- a/doc/build-waf.txt	Mon Jul 16 21:41:19 2007 -0700
     1.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.3 @@ -1,114 +0,0 @@
     1.4 -The main ns-3 build system is SCons.  Read the file build.txt
     1.5 -for SCons instructions.
     1.6 -
     1.7 -Waf is an alternative build system, similar to SCons.  ns-3 now is
     1.8 -able to build with Waf, in parallel to SCons.
     1.9 -
    1.10 -(http://www.freehackers.org/~tnagy/waf.html)
    1.11 -
    1.12 -Note: the Waf build scripts are experimental at this stage.
    1.13 -Gustavo Carneiro (gjcarneiro@gmail.com) is the maintainer.
    1.14 -
    1.15 -=== Building with Waf ===
    1.16 -
    1.17 -To build ns-3 with waf type the commands:
    1.18 - 1. waf configure [options]
    1.19 - 2. waf
    1.20 -
    1.21 -[ Note: if waf does not exist in your path, see the section 
    1.22 -"Note for developers" below ]
    1.23 -
    1.24 -To see valid configure options, type waf --help.  The most important
    1.25 -option is -d <debug level>.  Valid debug levels (which are listed in
    1.26 -waf --help) are: ultradebug, debug, release, and optimized.  It is
    1.27 -also possible to change the flags used for compilation with (e.g.):
    1.28 -CXXFLAGS="-O3" waf configure.
    1.29 -
    1.30 -[ Note:  Unlike some other build tools, to change the build target,
    1.31 -the option must be supplied during the configure stage rather than
    1.32 -the build stage (i.e., "waf -d optimized" will not work; instead, do
    1.33 -"waf -d optimized configure; waf" ]
    1.34 -
    1.35 -The resulting binaries are placed in build/<debuglevel>/srcpath.
    1.36 -
    1.37 -Other waf usages include:
    1.38 -
    1.39 - 1. waf check
    1.40 -    Runs the unit tests
    1.41 -
    1.42 - 2. waf --doxygen
    1.43 -    Run doxygen to generate documentation
    1.44 -
    1.45 - 3. waf --lcov-report
    1.46 -    Run code coverage analysis (assuming the project was configured
    1.47 -with --enable-gcov)
    1.48 -
    1.49 - 4. waf --run "program [args]"
    1.50 -    Run a ns3 program, given its target name, with the given
    1.51 -    arguments.  This takes care of automatically modifying the the
    1.52 -    path for finding the ns3 dynamic libraries in the environment
    1.53 -    before running the program.  Note: the "program [args]" string is
    1.54 -    parsed using POSIX shell rules.
    1.55 -
    1.56 - 5. waf --shell
    1.57 -    Starts a nested system shell with modified environment to run ns3 programs.
    1.58 -
    1.59 - 6. waf distclean
    1.60 -    Cleans out the entire build/ directory
    1.61 -
    1.62 - 7. waf dist
    1.63 -    The command 'waf dist' can be used to create a distribution tarball.
    1.64 -    It includes all files in the source directory, except some particular
    1.65 -    extensions that are blacklisted, such as back files (ending in ~).
    1.66 -
    1.67 -
    1.68 -=== Extending ns-3 ===
    1.69 -
    1.70 -To add new modules:
    1.71 -  1. Create the module directory under src (or src/devices, or whatever);
    1.72 -  2. Add the source files to it;
    1.73 -  3. Add a 'wscript' describing it;
    1.74 -  4. Add the module subdirectory name to the all_modules list in src/wscript.
    1.75 -
    1.76 -A module's wscript file is basically a regular Waf script.  A ns-3
    1.77 -module is created as a cpp/shlib object, like this:
    1.78 -
    1.79 -def build(bld):
    1.80 -    obj = bld.create_obj('cpp', 'shlib')
    1.81 -
    1.82 -    ## set module name; by convention it starts with ns3-
    1.83 -    obj.name = 'ns3-mymodule'
    1.84 -    obj.target = obj.name 
    1.85 -
    1.86 -    ## list dependencies to other modules
    1.87 -    obj.uselib_local = ['ns3-core'] 
    1.88 -
    1.89 -    ## list source files (private or public header files excluded)
    1.90 -    obj.source = [
    1.91 -        'mymodule.cc',
    1.92 -    ]
    1.93 -
    1.94 -    ## list module public header files
    1.95 -    headers = bld.create_obj('ns3header')
    1.96 -    headers.source = [
    1.97 -        'mymodule-header.h',
    1.98 -    ]
    1.99 -
   1.100 -
   1.101 -=== Note for developers ===
   1.102 -
   1.103 -The ns-3 code repository does not contain the waf script.  Instead,
   1.104 -developers should check it out from a subversion repository:
   1.105 -
   1.106 -  svn checkout http://waf.googlecode.com/svn/tags/ns3/ waf
   1.107 -
   1.108 -[ note: 'tags/ns3' is a tag that represents the last svn version
   1.109 -tested to work correctly with ns3, although 'trunk' will likely work
   1.110 - as well ]
   1.111 -
   1.112 -Then it can be installed system-wide with 'sudo waf-light install'.
   1.113 -When preparing a distribution, the resulting 'waf' script, which is
   1.114 -self contained (no external files needed), can be easily included in
   1.115 -the tarball so that users downloading ns-3 can easily build it without
   1.116 -having Waf installed (although Python >= 2.3 is still needed).
   1.117 -