author | Mathieu Lacage <mathieu.lacage@sophia.inria.fr> |
Wed, 10 Dec 2008 01:34:04 -0800 | |
changeset 4002 | a12900ea255e |
parent 3688 | e49a3c85cfd9 |
child 4064 | 10222f483860 |
permissions | -rw-r--r-- |
929 | 1 |
The Waf build system is used to build ns-3. Waf is a Python-based |
2 |
build system (http://www.freehackers.org/~tnagy/waf.html) |
|
3 |
||
3688 | 4 |
Note: We've added a wiki page with more complete build instructions |
5 |
than the quick ones you find below: |
|
6 |
http://www.nsnam.org/wiki/index.php/Installation |
|
7 |
||
929 | 8 |
=== Installing Waf === |
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
9 |
|
1788 | 10 |
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
|
11 |
|
929 | 12 |
=== Building with Waf === |
13 |
||
1788 | 14 |
To build ns-3 with waf type the commands from the top-level directory: |
15 |
1. ./waf configure [options] |
|
16 |
2. ./waf |
|
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
17 |
|
1788 | 18 |
To see valid configure options, type ./waf --help. The most important |
929 | 19 |
option is -d <debug level>. Valid debug levels (which are listed in |
1788 | 20 |
waf --help) are: "debug" or "optimized". It is |
929 | 21 |
also possible to change the flags used for compilation with (e.g.): |
1788 | 22 |
CXXFLAGS="-O3" ./waf configure. |
57
9385fba1589e
add doc target to BUILD file
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
17
diff
changeset
|
23 |
|
929 | 24 |
[ Note: Unlike some other build tools, to change the build target, |
25 |
the option must be supplied during the configure stage rather than |
|
1788 | 26 |
the build stage (i.e., "./waf -d optimized" will not work; instead, do |
27 |
"./waf -d optimized configure; ./waf" ] |
|
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
28 |
|
929 | 29 |
The resulting binaries are placed in build/<debuglevel>/srcpath. |
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
30 |
|
929 | 31 |
Other waf usages include: |
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
32 |
|
1788 | 33 |
1. ./waf check |
929 | 34 |
Runs the unit tests |
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
35 |
|
1788 | 36 |
2. ./waf --doxygen |
929 | 37 |
Run doxygen to generate documentation |
116
d4ee28e845f3
add lcov support
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
115
diff
changeset
|
38 |
|
1788 | 39 |
3. ./waf --lcov-report |
929 | 40 |
Run code coverage analysis (assuming the project was configured |
41 |
with --enable-gcov) |
|
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
42 |
|
1788 | 43 |
4. ./waf --run "program [args]" |
929 | 44 |
Run a ns3 program, given its target name, with the given |
45 |
arguments. This takes care of automatically modifying the the |
|
46 |
path for finding the ns3 dynamic libraries in the environment |
|
47 |
before running the program. Note: the "program [args]" string is |
|
48 |
parsed using POSIX shell rules. |
|
101
2437ccac8acd
add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
88
diff
changeset
|
49 |
|
1788 | 50 |
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
|
51 |
|
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 |
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
|
53 |
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
|
54 |
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
|
55 |
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
|
56 |
|
1788 | 57 |
./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
|
58 |
|
1788 | 59 |
5. ./waf --shell |
929 | 60 |
Starts a nested system shell with modified environment to run ns3 programs. |
61 |
||
1788 | 62 |
6. ./waf distclean |
929 | 63 |
Cleans out the entire build/ directory |
101
2437ccac8acd
add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
88
diff
changeset
|
64 |
|
1788 | 65 |
7. ./waf dist |
929 | 66 |
The command 'waf dist' can be used to create a distribution tarball. |
67 |
It includes all files in the source directory, except some particular |
|
68 |
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
|
69 |
|
929 | 70 |
=== Extending ns-3 === |
101
2437ccac8acd
add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
88
diff
changeset
|
71 |
|
929 | 72 |
To add new modules: |
73 |
1. Create the module directory under src (or src/devices, or whatever); |
|
74 |
2. Add the source files to it; |
|
75 |
3. Add a 'wscript' describing it; |
|
76 |
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
|
77 |
|
929 | 78 |
A module's wscript file is basically a regular Waf script. A ns-3 |
79 |
module is created as a cpp/shlib object, like this: |
|
80 |
||
81 |
def build(bld): |
|
82 |
obj = bld.create_obj('cpp', 'shlib') |
|
101
2437ccac8acd
add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
88
diff
changeset
|
83 |
|
929 | 84 |
## set module name; by convention it starts with ns3- |
85 |
obj.name = 'ns3-mymodule' |
|
86 |
obj.target = obj.name |
|
87 |
||
88 |
## list dependencies to other modules |
|
89 |
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
|
90 |
|
929 | 91 |
## list source files (private or public header files excluded) |
92 |
obj.source = [ |
|
93 |
'mymodule.cc', |
|
94 |
] |
|
95 |
||
96 |
## list module public header files |
|
97 |
headers = bld.create_obj('ns3header') |
|
98 |
headers.source = [ |
|
99 |
'mymodule-header.h', |
|
100 |
] |
|
101 |