doc/build.txt
author Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Thu, 17 Apr 2008 15:40:25 -0700
changeset 2971 75780f899be3
parent 1788 572cef188fdf
child 3688 e49a3c85cfd9
permissions -rw-r--r--
output the initial value of the attributes
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
1788
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
     6
The top-level ns-3 directory should contain a current waf script.
17
b959311b6aa1 build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
     7
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
     8
=== Building with Waf ===
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
     9
1788
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    10
To build ns-3 with waf type the commands from the top-level directory:
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    11
 1. ./waf configure [options]
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    12
 2. ./waf
17
b959311b6aa1 build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    13
1788
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    14
To see valid configure options, type ./waf --help.  The most important
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    15
option is -d <debug level>.  Valid debug levels (which are listed in
1788
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    16
waf --help) are: "debug" or "optimized".  It is
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    17
also possible to change the flags used for compilation with (e.g.):
1788
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    18
CXXFLAGS="-O3" ./waf configure.
57
9385fba1589e add doc target to BUILD file
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 17
diff changeset
    19
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    20
[ 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
    21
the option must be supplied during the configure stage rather than
1788
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    22
the build stage (i.e., "./waf -d optimized" will not work; instead, do
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    23
"./waf -d optimized configure; ./waf" ]
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
The resulting binaries are placed in build/<debuglevel>/srcpath.
17
b959311b6aa1 build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    26
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    27
Other waf usages include:
17
b959311b6aa1 build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    28
1788
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    29
 1. ./waf check
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    30
    Runs the unit tests
17
b959311b6aa1 build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    31
1788
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    32
 2. ./waf --doxygen
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    33
    Run doxygen to generate documentation
116
d4ee28e845f3 add lcov support
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 115
diff changeset
    34
1788
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    35
 3. ./waf --lcov-report
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    36
    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
    37
with --enable-gcov)
17
b959311b6aa1 build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff changeset
    38
1788
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    39
 4. ./waf --run "program [args]"
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    40
    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
    41
    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
    42
    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
    43
    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
    44
    parsed using POSIX shell rules.
101
2437ccac8acd add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 88
diff changeset
    45
1788
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    46
 4.1 ./waf --run programname --command-template "... %s ..."
935
53e1e53c373f WAF: add a --command-template option to e.g. allow running programs with valgrind, gdb, etc.
Gustavo J. A. M. Carneiro <gjc@inescporto.pt>
parents: 934
diff changeset
    47
53e1e53c373f WAF: add a --command-template option to e.g. allow running programs with valgrind, gdb, etc.
Gustavo J. A. M. Carneiro <gjc@inescporto.pt>
parents: 934
diff changeset
    48
    Same as --run, but uses a command template with %s replaced by the
53e1e53c373f WAF: add a --command-template option to e.g. allow running programs with valgrind, gdb, etc.
Gustavo J. A. M. Carneiro <gjc@inescporto.pt>
parents: 934
diff changeset
    49
    actual program (whose name is given by --run).  This can be use to
53e1e53c373f WAF: add a --command-template option to e.g. allow running programs with valgrind, gdb, etc.
Gustavo J. A. M. Carneiro <gjc@inescporto.pt>
parents: 934
diff changeset
    50
    run ns-3 programs with helper tools.  For example, to run unit
53e1e53c373f WAF: add a --command-template option to e.g. allow running programs with valgrind, gdb, etc.
Gustavo J. A. M. Carneiro <gjc@inescporto.pt>
parents: 934
diff changeset
    51
    tests with valgrind, use the command:
53e1e53c373f WAF: add a --command-template option to e.g. allow running programs with valgrind, gdb, etc.
Gustavo J. A. M. Carneiro <gjc@inescporto.pt>
parents: 934
diff changeset
    52
1788
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    53
         ./waf --run run-tests --command-template "valgrind %s"
935
53e1e53c373f WAF: add a --command-template option to e.g. allow running programs with valgrind, gdb, etc.
Gustavo J. A. M. Carneiro <gjc@inescporto.pt>
parents: 934
diff changeset
    54
1788
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    55
 5. ./waf --shell
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    56
    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
    57
1788
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    58
 6. ./waf distclean
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    59
    Cleans out the entire build/ directory
101
2437ccac8acd add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 88
diff changeset
    60
1788
572cef188fdf updates for 3.0.7
Tom Henderson <tomh@tomh.org>
parents: 935
diff changeset
    61
 7. ./waf dist
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    62
    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
    63
    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
    64
    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
    65
2437ccac8acd add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 88
diff changeset
    66
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    67
=== Extending ns-3 ===
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
To add new modules:
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    70
  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
    71
  2. Add the source files to it;
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    72
  3. Add a 'wscript' describing it;
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    73
  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
    74
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    75
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
    76
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
    77
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    78
def build(bld):
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    79
    obj = bld.create_obj('cpp', 'shlib')
101
2437ccac8acd add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents: 88
diff changeset
    80
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    81
    ## 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
    82
    obj.name = 'ns3-mymodule'
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    83
    obj.target = obj.name 
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    84
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    85
    ## list dependencies to other modules
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    86
    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
    87
929
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    88
    ## 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
    89
    obj.source = [
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    90
        'mymodule.cc',
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    91
    ]
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 module public header files
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    94
    headers = bld.create_obj('ns3header')
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    95
    headers.source = [
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    96
        'mymodule-header.h',
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    97
    ]
9394956b7fc4 changes for 3.0.4 release
Tom Henderson <tomh@tomh.org>
parents: 658
diff changeset
    98