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-- |
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 |
||
4 |
=== Installing Waf === |
|
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
5 |
|
929 | 6 |
If this file is part of a development release tarball, the top-level |
7 |
ns-3 directory should contain a current waf script. |
|
8 |
||
9 |
However, the ns-3 Mercurial code repository does not contain the waf |
|
10 |
script. Instead, developers should check it out from a subversion |
|
11 |
repository: |
|
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
12 |
|
929 | 13 |
svn checkout http://waf.googlecode.com/svn/tags/ns3/ waf |
14 |
||
15 |
[ note: 'tags/ns3' is a tag that represents the last svn version |
|
16 |
tested to work correctly with ns3, although 'trunk' will likely work |
|
17 |
as well ] |
|
87
a1b7dc32df30
beautify build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
57
diff
changeset
|
18 |
|
929 | 19 |
Then it can be installed system-wide with 'sudo waf-light install'. |
20 |
When preparing a distribution, the resulting 'waf' script, which is |
|
21 |
self contained (no external files needed), can be easily included in |
|
22 |
the tarball so that users downloading ns-3 can easily build it without |
|
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 | 25 |
=== Building with Waf === |
26 |
||
27 |
To build ns-3 with waf type the commands: |
|
28 |
1. waf configure [options] |
|
29 |
2. waf |
|
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
30 |
|
929 | 31 |
To see valid configure options, type waf --help. The most important |
32 |
option is -d <debug level>. Valid debug levels (which are listed in |
|
33 |
waf --help) are: ultradebug, debug, release, and optimized. It is |
|
34 |
also possible to change the flags used for compilation with (e.g.): |
|
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 | 37 |
[ Note: Unlike some other build tools, to change the build target, |
38 |
the option must be supplied during the configure stage rather than |
|
39 |
the build stage (i.e., "waf -d optimized" will not work; instead, do |
|
40 |
"waf -d optimized configure; waf" ] |
|
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
41 |
|
929 | 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 | 44 |
Other waf usages include: |
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
45 |
|
929 | 46 |
1. waf check |
47 |
Runs the unit tests |
|
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
48 |
|
929 | 49 |
2. waf --doxygen |
50 |
Run doxygen to generate documentation |
|
116
d4ee28e845f3
add lcov support
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
115
diff
changeset
|
51 |
|
929 | 52 |
3. waf --lcov-report |
53 |
Run code coverage analysis (assuming the project was configured |
|
54 |
with --enable-gcov) |
|
17
b959311b6aa1
build instructions
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
diff
changeset
|
55 |
|
929 | 56 |
4. waf --run "program [args]" |
57 |
Run a ns3 program, given its target name, with the given |
|
58 |
arguments. This takes care of automatically modifying the the |
|
59 |
path for finding the ns3 dynamic libraries in the environment |
|
60 |
before running the program. Note: the "program [args]" string is |
|
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 | 63 |
5. waf --shell |
64 |
Starts a nested system shell with modified environment to run ns3 programs. |
|
65 |
||
66 |
6. waf distclean |
|
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 | 69 |
7. waf dist |
70 |
The command 'waf dist' can be used to create a distribution tarball. |
|
71 |
It includes all files in the source directory, except some particular |
|
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 | 75 |
=== Extending ns-3 === |
101
2437ccac8acd
add documentation on build system
Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
parents:
88
diff
changeset
|
76 |
|
929 | 77 |
To add new modules: |
78 |
1. Create the module directory under src (or src/devices, or whatever); |
|
79 |
2. Add the source files to it; |
|
80 |
3. Add a 'wscript' describing it; |
|
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 | 83 |
A module's wscript file is basically a regular Waf script. A ns-3 |
84 |
module is created as a cpp/shlib object, like this: |
|
85 |
||
86 |
def build(bld): |
|
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 | 89 |
## set module name; by convention it starts with ns3- |
90 |
obj.name = 'ns3-mymodule' |
|
91 |
obj.target = obj.name |
|
92 |
||
93 |
## list dependencies to other modules |
|
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 | 96 |
## list source files (private or public header files excluded) |
97 |
obj.source = [ |
|
98 |
'mymodule.cc', |
|
99 |
] |
|
100 |
||
101 |
## list module public header files |
|
102 |
headers = bld.create_obj('ns3header') |
|
103 |
headers.source = [ |
|
104 |
'mymodule-header.h', |
|
105 |
] |
|
106 |