1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
If you want to build ns3, you need to install scons (see
http://www.scons.org). scons takes care of building
the whole source tree using your system compiler. scons
0.91.1 and 0.91.96 have been tested and are known to
work on linux FC5, Mac os X and MinGW.
To start a build, you can just type 'scons' which
will generate a debug shared build by default, located
in the directory 'build-dir/dbg-shared/bin' and
'build-dir/dbg-shared/lib'.
All builds are built with debugging symbols. Debugging
builds enable asserts while optimized builds disable them.
On platforms which support it, rpath is used which means that
the executable binaries generated link explicitely against
the right libraries. This saves you the pain of having to
setup environment variables to point to the right libraries.
1) Options
----------
- verbose: if you have installed scons 0.91.96 or higher,
the default build output is terse. To get a more verbose
output, you need to set the 'verbose' variable to 'y'.
Example: scons verbose=y
- cflags: flags for the C compiler.
Example: scons cflags="-O3 -ffast-math"
- cxxflags: flags for the C++ compiler.
Example: scons cxxflags="-O3 -ffast-math"
- ldflags: flags for the linker:
Example: scons ldflags="-L/foo -L/bar"
- high-precision-as-double: set to 'y' to make sure that the
high-precision arithmetics performed by the Time class on
behalf of the user will use doubles. By default, the code
uses 128 integers.
Example: scons high-precision-as-double=y
- inheritenv: set to 'y' if you want to make your compiler
execute within the same environment (env vars) as your own
shell. This is typically used to make colorgcc work.
Example: scons inheritenv=y
2) Targets
----------
- doc: build the doxygen documentation.
Example: scons doc
- dbg-shared: a debug build using shared libraries.
The files are built in 'build-dir/dbg-shared/'.
Example: scons dbg-shared
- dbg-static: a debug build using static libraries
The files are built in 'build-dir/dbg-static/'.
Example: scons dbg-static
- opt-shared: an optimized build using shared libraries.
The files are built in 'build-dir/opt-shared/'.
Example: scons opt-shared
- opt-static: an optimized build using static libraries.
The files are built in 'build-dir/opt-static/'.
Example: scons opt-static
- dbg: an alias for dbg-shared
Example: scons dbg
- opt: an alias for opt-shared
Example: scons opt
- all: alias for dbg-shared, dbg-static, opt-shared
and opt-static
Example: scons all
- gcov: code coverage analysis. Build a debugging version of
the code for code coverage analysis in 'build-dir/gcov'. Once
the code has been built, you can run various applications to
exercise the code paths. To generate an html report from
the gcov data, use the lcov-report target
- lcov-report: generate html report of gcov data. The output
is stored in 'build-dir/lcov-report/'.
- dist: generate a release tarball and zipfile from the
source tree. The tarball and zipfile name are generated
according to the version number stored in the SConstruct
file.
Example in SConstruct:
ns3 = Ns3 ()
ns3.name = 'foo'
ns3.version = '0.0.10'
Example command: scons dist
Example output files:
foo-0.0.10.tar.gz
foo-0.0.10.zip
- distcheck: generate a release tarball and zipfile and
attempt to run the 'all' target for the release tarball.
Example: scons distcheck
3) How the build system works
-----------------------------
The current build system defines what are called "ns3 modules": each module
is a set of source files, normal header files and installable header
files. Each module also depends on a set of other modules. We build
modules automatically in the correct order. That is, we always start
from the module which does not depend on any other module (core) and
proceed with the other modules and make sure that when a module is
built, all the modules it depends upon have already been built.
To build a module, we:
1) generate the .o files
2) link the .o files together
3) install the installable headers in the common directory
top_build_dir/include/ns3.
This means that if you want to use a header from your own module, you
should just include it: #include "foo.h" but if you want to include a
header from another module, you need to include it with #include
"ns3/bar.h". This allows you to make sure that our "public" ns3 headers
do not conflict with existing system-level headers. For instance,
if you were to define a header called queue.h, you would include
ns3/queue.h rather than queue.h, when including from a separate module,
since many systems provide a queue.h system include file.
4) How to add files to a module ?
---------------------------------
In the main SConstruct file, you can add source code
to the add_sources method. For example, to add a foo.cc
file to the core module, we coud do this:
core.add_sources ('foo.cc')
Of course, if this file implements public API, its
header should be installable:
core.add_inst_headers ('foo.h')
5) How to create a new module ?
-------------------------------
# create a new module. First arg is the name of
# the new module. Second arg is the directory in
# which all source files for this module reside.
my_module = build.Ns3Module ('my', 'src/my_dir')
# add it to build system
ns3.add (my_module)
# specify module dependencies. Here, depends
# on the 'ipv4' and 'core' modules
my_module.add_deps (['core', 'ipv4'])
# add source code to build located in
# src/my_dir
my_module.add_sources ([
'my_a.cc',
'my_b.cc',
'my_c.cc'
])
my_module.add_sources ([
'my_d.cc'
])
# add headers which are not public
my_module.add_headers ([
'my_a.h',
'my_c.h'
])
# add headers which are public
my_module.add_inst_headers ([
'my_b.h'
])
my_module.add_inst_headers ([
'my_d.h'
])
# if you need to link against an external library,
# you must add 'external' dependencies. Here, the
# pthread library
my_module.add_external_dep ('pthread')
# by default, a module is conceptually a library. If you
# want to generate an executable from a module you need to:
my_module.set_executable ()