doc/build.txt
author Tom Henderson <tomh@tomh.org>
Mon, 16 Jul 2007 21:41:19 -0700
changeset 929 9394956b7fc4
parent 658 32307a281d86
child 933 df68dad55087
permissions -rw-r--r--
changes for 3.0.4 release
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
     1
The Waf build system is used to build ns-3.  Waf is a Python-based
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
     2
build system (http://www.freehackers.org/~tnagy/waf.html)
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
     3
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
     4
=== Installing Waf ===
17
b959311b6aa1 build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
     5
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
     6
If this file is part of a development release tarball, the top-level 
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
     7
ns-3 directory should contain a current waf script.
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
     8
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
     9
However, the ns-3 Mercurial code repository does not contain the waf 
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    10
script.  Instead, developers should check it out from a subversion 
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    11
repository:
17
b959311b6aa1 build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    12
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    13
  svn checkout http://waf.googlecode.com/svn/tags/ns3/ waf
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    14
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    15
[ note: 'tags/ns3' is a tag that represents the last svn version
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    16
tested to work correctly with ns3, although 'trunk' will likely work
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    17
 as well ]
87
a1b7dc32df30 beautify build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 57
diff changeset
    18
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    19
Then it can be installed system-wide with 'sudo waf-light install'.
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    20
When preparing a distribution, the resulting 'waf' script, which is
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    21
self contained (no external files needed), can be easily included in
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    22
the tarball so that users downloading ns-3 can easily build it without
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    23
having Waf installed (although Python >= 2.3 is still needed).
17
b959311b6aa1 build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    24
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    25
=== Building with Waf ===
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    26
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    27
To build ns-3 with waf type the commands:
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    28
 1. waf configure [options]
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    29
 2. waf
17
b959311b6aa1 build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    30
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    31
To see valid configure options, type waf --help.  The most important
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    32
option is -d <debug level>.  Valid debug levels (which are listed in
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    33
waf --help) are: ultradebug, debug, release, and optimized.  It is
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    34
also possible to change the flags used for compilation with (e.g.):
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    35
CXXFLAGS="-O3" waf configure.
57
9385fba1589e add doc target to BUILD file
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 17
diff changeset
    36
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    37
[ Note:  Unlike some other build tools, to change the build target,
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    38
the option must be supplied during the configure stage rather than
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    39
the build stage (i.e., "waf -d optimized" will not work; instead, do
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    40
"waf -d optimized configure; waf" ]
17
b959311b6aa1 build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    41
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    42
The resulting binaries are placed in build/<debuglevel>/srcpath.
17
b959311b6aa1 build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    43
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    44
Other waf usages include:
17
b959311b6aa1 build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    45
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    46
 1. waf check
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    47
    Runs the unit tests
17
b959311b6aa1 build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    48
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    49
 2. waf --doxygen
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    50
    Run doxygen to generate documentation
116
d4ee28e845f3 add lcov support
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 115
diff changeset
    51
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    52
 3. waf --lcov-report
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    53
    Run code coverage analysis (assuming the project was configured
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    54
with --enable-gcov)
17
b959311b6aa1 build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    55
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    56
 4. waf --run "program [args]"
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    57
    Run a ns3 program, given its target name, with the given
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    58
    arguments.  This takes care of automatically modifying the the
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    59
    path for finding the ns3 dynamic libraries in the environment
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    60
    before running the program.  Note: the "program [args]" string is
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    61
    parsed using POSIX shell rules.
101
2437ccac8acd add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 88
diff changeset
    62
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    63
 5. waf --shell
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    64
    Starts a nested system shell with modified environment to run ns3 programs.
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    65
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    66
 6. waf distclean
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    67
    Cleans out the entire build/ directory
101
2437ccac8acd add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 88
diff changeset
    68
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    69
 7. waf dist
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    70
    The command 'waf dist' can be used to create a distribution tarball.
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    71
    It includes all files in the source directory, except some particular
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    72
    extensions that are blacklisted, such as back files (ending in ~).
101
2437ccac8acd add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 88
diff changeset
    73
2437ccac8acd add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 88
diff changeset
    74
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    75
=== Extending ns-3 ===
101
2437ccac8acd add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 88
diff changeset
    76
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    77
To add new modules:
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    78
  1. Create the module directory under src (or src/devices, or whatever);
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    79
  2. Add the source files to it;
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    80
  3. Add a 'wscript' describing it;
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    81
  4. Add the module subdirectory name to the all_modules list in src/wscript.
101
2437ccac8acd add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 88
diff changeset
    82
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    83
A module's wscript file is basically a regular Waf script.  A ns-3
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    84
module is created as a cpp/shlib object, like this:
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    85
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    86
def build(bld):
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    87
    obj = bld.create_obj('cpp', 'shlib')
101
2437ccac8acd add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 88
diff changeset
    88
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    89
    ## set module name; by convention it starts with ns3-
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    90
    obj.name = 'ns3-mymodule'
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    91
    obj.target = obj.name 
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    92
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    93
    ## list dependencies to other modules
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    94
    obj.uselib_local = ['ns3-core'] 
168
037cd2b37c67 split high precision implementations in different files
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 125
diff changeset
    95
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    96
    ## list source files (private or public header files excluded)
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    97
    obj.source = [
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    98
        'mymodule.cc',
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    99
    ]
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
   100
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
   101
    ## list module public header files
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
   102
    headers = bld.create_obj('ns3header')
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
   103
    headers.source = [
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
   104
        'mymodule-header.h',
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
   105
    ]
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
   106