author | Gustavo J. A. M. Carneiro <gjc@inescporto.pt> |
Fri, 03 Jul 2009 14:12:28 +0100 | |
changeset 4649 | 189238bfdc7f |
parent 4534 | 2680abc768f2 |
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 |
|
4064
10222f483860
Upgrade to new WAF, work in progress
Gustavo J. A. M. Carneiro <gjc@inescporto.pt>
parents:
3688
diff
changeset
|
12 |
Note: we're using a WAF version based on WAF 1.5.x. The source code |
10222f483860
Upgrade to new WAF, work in progress
Gustavo J. A. M. Carneiro <gjc@inescporto.pt>
parents:
3688
diff
changeset
|
13 |
can be retrieved from the followin URL: |
10222f483860
Upgrade to new WAF, work in progress
Gustavo J. A. M. Carneiro <gjc@inescporto.pt>
parents:
3688
diff
changeset
|
14 |
|
10222f483860
Upgrade to new WAF, work in progress
Gustavo J. A. M. Carneiro <gjc@inescporto.pt>
parents:
3688
diff
changeset
|
15 |
https://code.launchpad.net/~gjc/waf/cmd |
10222f483860
Upgrade to new WAF, work in progress
Gustavo J. A. M. Carneiro <gjc@inescporto.pt>
parents:
3688
diff
changeset
|
16 |
|
10222f483860
Upgrade to new WAF, work in progress
Gustavo J. A. M. Carneiro <gjc@inescporto.pt>
parents:
3688
diff
changeset
|
17 |
|
929 | 18 |
=== Building with Waf === |
19 |
||
1788 | 20 |
To build ns-3 with waf type the commands from the top-level directory: |
21 |
1. ./waf configure [options] |
|
22 |
2. ./waf |
|
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
23 |
|
1788 | 24 |
To see valid configure options, type ./waf --help. The most important |
929 | 25 |
option is -d <debug level>. Valid debug levels (which are listed in |
1788 | 26 |
waf --help) are: "debug" or "optimized". It is |
929 | 27 |
also possible to change the flags used for compilation with (e.g.): |
1788 | 28 |
CXXFLAGS="-O3" ./waf configure. |
57
9385fba1589e
add doc target to BUILD file
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
17
diff
changeset
|
29 |
|
929 | 30 |
[ Note: Unlike some other build tools, to change the build target, |
31 |
the option must be supplied during the configure stage rather than |
|
1788 | 32 |
the build stage (i.e., "./waf -d optimized" will not work; instead, do |
33 |
"./waf -d optimized configure; ./waf" ] |
|
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
34 |
|
929 | 35 |
The resulting binaries are placed in build/<debuglevel>/srcpath. |
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
36 |
|
929 | 37 |
Other waf usages include: |
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
38 |
|
4534
2680abc768f2
update dox for waf --check
Craig Dowell <craigdo@ee.washington.edu>
parents:
4064
diff
changeset
|
39 |
1. ./waf --check |
929 | 40 |
Runs the unit tests |
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
41 |
|
1788 | 42 |
2. ./waf --doxygen |
929 | 43 |
Run doxygen to generate documentation |
116
d4ee28e845f3
add lcov support
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
115
diff
changeset
|
44 |
|
1788 | 45 |
3. ./waf --lcov-report |
929 | 46 |
Run code coverage analysis (assuming the project was configured |
47 |
with --enable-gcov) |
|
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
48 |
|
1788 | 49 |
4. ./waf --run "program [args]" |
929 | 50 |
Run a ns3 program, given its target name, with the given |
51 |
arguments. This takes care of automatically modifying the the |
|
52 |
path for finding the ns3 dynamic libraries in the environment |
|
53 |
before running the program. Note: the "program [args]" string is |
|
54 |
parsed using POSIX shell rules. |
|
101
2437ccac8acd
add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
88
diff
changeset
|
55 |
|
1788 | 56 |
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
|
57 |
|
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 |
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
|
59 |
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
|
60 |
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
|
61 |
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
|
62 |
|
1788 | 63 |
./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
|
64 |
|
1788 | 65 |
5. ./waf --shell |
929 | 66 |
Starts a nested system shell with modified environment to run ns3 programs. |
67 |
||
1788 | 68 |
6. ./waf distclean |
929 | 69 |
Cleans out the entire build/ directory |
101
2437ccac8acd
add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
88
diff
changeset
|
70 |
|
1788 | 71 |
7. ./waf dist |
929 | 72 |
The command 'waf dist' can be used to create a distribution tarball. |
73 |
It includes all files in the source directory, except some particular |
|
74 |
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
|
75 |
|
929 | 76 |
=== Extending ns-3 === |
101
2437ccac8acd
add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
88
diff
changeset
|
77 |
|
929 | 78 |
To add new modules: |
79 |
1. Create the module directory under src (or src/devices, or whatever); |
|
80 |
2. Add the source files to it; |
|
81 |
3. Add a 'wscript' describing it; |
|
82 |
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
|
83 |
|
929 | 84 |
A module's wscript file is basically a regular Waf script. A ns-3 |
85 |
module is created as a cpp/shlib object, like this: |
|
86 |
||
87 |
def build(bld): |
|
88 |
obj = bld.create_obj('cpp', 'shlib') |
|
101
2437ccac8acd
add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
88
diff
changeset
|
89 |
|
929 | 90 |
## set module name; by convention it starts with ns3- |
91 |
obj.name = 'ns3-mymodule' |
|
92 |
obj.target = obj.name |
|
93 |
||
94 |
## list dependencies to other modules |
|
95 |
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
|
96 |
|
929 | 97 |
## list source files (private or public header files excluded) |
98 |
obj.source = [ |
|
99 |
'mymodule.cc', |
|
100 |
] |
|
101 |
||
102 |
## list module public header files |
|
103 |
headers = bld.create_obj('ns3header') |
|
104 |
headers.source = [ |
|
105 |
'mymodule-header.h', |
|
106 |
] |
|
107 |