107 lines
3.5 KiB
Plaintext
107 lines
3.5 KiB
Plaintext
The Waf build system is used to build ns-3. Waf is a Python-based
|
|
build system (http://www.freehackers.org/~tnagy/waf.html)
|
|
|
|
=== Installing Waf ===
|
|
|
|
If this file is part of a development release tarball, the top-level
|
|
ns-3 directory should contain a current waf script.
|
|
|
|
However, the ns-3 Mercurial code repository does not contain the waf
|
|
script. Instead, developers should check it out from a subversion
|
|
repository:
|
|
|
|
svn checkout http://waf.googlecode.com/svn/tags/ns3/ waf
|
|
|
|
[ note: 'tags/ns3' is a tag that represents the last svn version
|
|
tested to work correctly with ns3, although 'trunk' will likely work
|
|
as well ]
|
|
|
|
Then it can be installed system-wide with 'sudo waf-light install'.
|
|
When preparing a distribution, the resulting 'waf' script, which is
|
|
self contained (no external files needed), can be easily included in
|
|
the tarball so that users downloading ns-3 can easily build it without
|
|
having Waf installed (although Python >= 2.3 is still needed).
|
|
|
|
=== Building with Waf ===
|
|
|
|
To build ns-3 with waf type the commands:
|
|
1. waf configure [options]
|
|
2. waf
|
|
|
|
To see valid configure options, type waf --help. The most important
|
|
option is -d <debug level>. Valid debug levels (which are listed in
|
|
waf --help) are: ultradebug, debug, release, and optimized. It is
|
|
also possible to change the flags used for compilation with (e.g.):
|
|
CXXFLAGS="-O3" waf configure.
|
|
|
|
[ Note: Unlike some other build tools, to change the build target,
|
|
the option must be supplied during the configure stage rather than
|
|
the build stage (i.e., "waf -d optimized" will not work; instead, do
|
|
"waf -d optimized configure; waf" ]
|
|
|
|
The resulting binaries are placed in build/<debuglevel>/srcpath.
|
|
|
|
Other waf usages include:
|
|
|
|
1. waf check
|
|
Runs the unit tests
|
|
|
|
2. waf --doxygen
|
|
Run doxygen to generate documentation
|
|
|
|
3. waf --lcov-report
|
|
Run code coverage analysis (assuming the project was configured
|
|
with --enable-gcov)
|
|
|
|
4. waf --run "program [args]"
|
|
Run a ns3 program, given its target name, with the given
|
|
arguments. This takes care of automatically modifying the the
|
|
path for finding the ns3 dynamic libraries in the environment
|
|
before running the program. Note: the "program [args]" string is
|
|
parsed using POSIX shell rules.
|
|
|
|
5. waf --shell
|
|
Starts a nested system shell with modified environment to run ns3 programs.
|
|
|
|
6. waf distclean
|
|
Cleans out the entire build/ directory
|
|
|
|
7. waf dist
|
|
The command 'waf dist' can be used to create a distribution tarball.
|
|
It includes all files in the source directory, except some particular
|
|
extensions that are blacklisted, such as back files (ending in ~).
|
|
|
|
|
|
=== Extending ns-3 ===
|
|
|
|
To add new modules:
|
|
1. Create the module directory under src (or src/devices, or whatever);
|
|
2. Add the source files to it;
|
|
3. Add a 'wscript' describing it;
|
|
4. Add the module subdirectory name to the all_modules list in src/wscript.
|
|
|
|
A module's wscript file is basically a regular Waf script. A ns-3
|
|
module is created as a cpp/shlib object, like this:
|
|
|
|
def build(bld):
|
|
obj = bld.create_obj('cpp', 'shlib')
|
|
|
|
## set module name; by convention it starts with ns3-
|
|
obj.name = 'ns3-mymodule'
|
|
obj.target = obj.name
|
|
|
|
## list dependencies to other modules
|
|
obj.uselib_local = ['ns3-core']
|
|
|
|
## list source files (private or public header files excluded)
|
|
obj.source = [
|
|
'mymodule.cc',
|
|
]
|
|
|
|
## list module public header files
|
|
headers = bld.create_obj('ns3header')
|
|
headers.source = [
|
|
'mymodule-header.h',
|
|
]
|
|
|